<h2>DESCRIPTION</h2>

<em>i.cluster</em> performs the first pass in the two-pass
unsupervised classification of imagery, while the GRASS module <em>
<a href="i.maxlik.html">i.maxlik</a></em> executes the second pass.
Both commands must be run to complete the unsupervised classification.

<p>
<em>i.cluster</em> is a clustering algorithm (a modification of the
<i>k</i>-means clustering algorithm) that reads through the (raster) imagery
data and builds pixel clusters based on the spectral reflectances of the
pixels (see Figure).
The pixel clusters are imagery categories that can be related
to land cover types on the ground. The spectral distributions of the
clusters (e.g., land cover spectral signatures) are influenced by six
parameters set by the user. A relevant parameter set by the user is the
initial number of clusters to be discriminated.

<p>
<center>
<img src="i_cluster_landsat_clustering.png" border=1><br>
<table border=0 width=590>
<tr><td><center>
<i>Fig.: Land use/land cover clustering of LANDSAT scene (simplified)</i>
</center></td></tr>
</table>
</center>

<p>
<em>i.cluster</em> starts by generating spectral signatures
for this number of clusters and "attempts" to end up with
this number of clusters during the clustering process.  The
resulting number of clusters and their spectral
distributions, however, are also influenced by the range of
the spectral values (category values) in the image files
and the other parameters set by the user.  These parameters
are:  the minimum cluster size, minimum cluster separation,
the percent convergence, the maximum number of iterations,
and the row and column sampling intervals.

<p>
The cluster spectral signatures that result are composed of
cluster means and covariance matrices.  These cluster means
and covariance matrices are used in the second pass 
(<em><a href="i.maxlik.html">i.maxlik</a></em>) to
classify the image.  The clusters or spectral classes
result can be related to land cover types on the ground.

The user has to specify the name of group file, the name of subgroup
file, the name of a file to contain result signatures, the
initial number of clusters to be discriminated, and
optionally other parameters (see below)
where the <em>group</em> should contain the imagery files
that the user wishes to classify.  The <em>subgroup</em> is
a subset of this group.  The user must create a group and
subgroup by running the GRASS program

<em><a href="i.group.html">i.group</a></em> 

before running <em>i.cluster</em>.  The subgroup should
contain only the imagery band files that the user wishes to
classify.  Note that this subgroup must contain more than
one band file.  The purpose of the group and subgroup is to
collect map layers for classification or analysis. The
<em>signaturefile</em> is the file to contain result signatures
which can be used as input for

<em><a href="i.maxlik.html">i.maxlik</a></em>. 

The classes value is the initial number of clusters to be
discriminated; any parameter values left unspecified are
set to their default values.

<p>
All raster maps used to generate signature file must have band reference
set. Use <em><a href="r.support.html">r.support</a></em> to set
band references of each member of the imagery group.
Signatures generated for one scene are suitable for classification
of other scenes as long as they consist of same raster bands
(band references match).

<h3>Parameters:</h3>

<dl>
<dt><b>group=</b><em>name</em> 

<dd>The name of the group file which contains the imagery
files that the user wishes to classify.

<dt><b>subgroup=</b><em>name</em> 

<dd>The name of the subset of the group specified in group
option, which must contain only imagery band files and more
than one band file. The user must create a group and a
subgroup by running the GRASS program 

<em><a href="i.group.html">i.group</a></em> 

before
running <em>i.cluster</em>.

<dt><b>signaturefile=</b><em>name</em> 

<dd>The name assigned to output signature file which
contains signatures of classes and can be used as the input
file for the GRASS program 
<em><a href="i.maxlik.html">i.maxlik</a></em> 
for an unsupervised classification.

<dt><b>classes=</b><em>value</em> 

<dd>The number of clusters that will initially be
identified in the clustering process before the iterations
begin.

<dt><b>seed=</b><em>name</em> 

<dd>The name of a seed signature file is optional. The seed
signatures are signatures that contain cluster means and
covariance matrices which were calculated prior to the
current run of <em>i.cluster</em>. They may be acquired
from a previously run of <em>i.cluster</em> or from a
supervised classification signature training site section
(e.g., using the signature file output by

<em><a href="g.gui.iclass.html">g.gui.iclass</a></em>). 

The purpose of seed signatures is to optimize the cluster
decision boundaries (means) for the number of clusters
specified.

<dt><b>sample=</b><em>rows,cols</em> 

<dd>These numbers are optional with default values based on
the size of the data set such that the total pixels to be
processed is approximately 10,000 (consider round up). The 
smaller these numbers, the larger the sample size used to
generate the signatures for the classes defined.

<dt><b>iterations=</b><em>value</em> 

<dd>This parameter determines the maximum number of
iterations which is greater than the number of iterations
predicted to achieve the optimum percent convergence. The
default value is 30. If the number of iterations reaches
the maximum designated by the user; the user may want to
rerun <em>i.cluster</em> with a higher number of iterations
(see <a href="#reportfile"><em>reportfile</em></a>).

<br>

Default: 30

<a name="convergence"></a>
<dt><b>convergence=</b><em>value</em>

<dd>A high percent convergence is the point at which
cluster means become stable during the iteration process.
The default value is 98.0 percent.  When clusters are being
created, their means constantly change as pixels are
assigned to them and the means are recalculated to include
the new pixel.  After all clusters have been created,
<em>i.cluster</em> begins iterations that change cluster
means by maximizing the distances between them.  As these
means shift, a higher and higher convergence is
approached.  Because means will never become totally
static, a percent convergence and a maximum number of
iterations are supplied to stop the iterative process.  The
percent convergence should be reached before the maximum
number of iterations. If the maximum number of iterations
is reached, it is probable that the desired percent
convergence was not reached. The number of iterations is
reported in the cluster statistics in the report file
(see <a href="#reportfile"><em>reportfile</em></a>).

<br>

Default: 98.0

<dt><b>separation=</b><em>value</em> 

<dd>This is the minimum separation below which clusters
will be merged in the iteration process. The default value
is 0.0. This is an image-specific number (a "magic" number)
that depends on the image data being classified and the
number of final clusters that are acceptable. Its
determination requires experimentation. Note that as the
minimum class (or cluster) separation is increased, the
maximum number of iterations should also be increased to
achieve this separation with a high percentage of
convergence
(see <a href="#convergence"><em>convergence</em></a>).

<br>
Default: 0.0

<dt><b>min_size=</b><em>value</em> 

<dd>This is the minimum number of pixels that will be used
to define a cluster, and is therefore the minimum number of
pixels for which means and covariance matrices will be
calculated.

<br>
Default: 17

<A NAME="reportfile"></a>
<dt><b>reportfile=</b><em>name</em>

<dd>The reportfile is an optional parameter which contains
the result, i.e., the statistics for each cluster. Also
included are the resulting percent convergence for the
clusters, the number of iterations that was required to
achieve the convergence, and the separability matrix.
</dl>

<h2>NOTES</h2>

<h3>Sampling method</h3>

<em>i.cluster</em> does not cluster all pixels, but only a sample (see
parameter <b>sample</b>). The result of that clustering is not that all
pixels are assigned to a given cluster; essentially, only signatures which are
representative of a given cluster are generated. When running <em>i.cluster</em>
on the same data asking for the same number of classes, but with different
sample sizes, likely slightly different signatures for each cluster are
obtained at each run.

<h3>Algorithm used for i.cluster</h3>

<!-- cited after Harini Nagendra, "algorithm used for i.cluster"
     http://lists.osgeo.org/pipermail/grass-user/1997-December/000912.html
-->

The algorithm uses input parameters set by the user on the
initial number of clusters, the minimum distance between clusters, and the
correspondence between iterations which is desired, and minimum size for
each cluster. It also asks if all pixels to be clustered, or every "x"th row
and "y"th column (sampling), the correspondence between iterations
desired, and the maximum number of iterations to be carried out.
<p>
In the 1st pass, initial cluster means for each band are defined by giving
the first cluster a value equal to the band mean minus its standard
deviation, and the last cluster a value equal to the band mean plus its
standard deviation, with all other cluster means distributed equally
spaced in between these. Each pixel is then assigned to the class which it
is closest to, distance being measured as Euclidean distance. All clusters
less than the user-specified minimum distance are then merged. If a
cluster has less than the user-specified minimum number of pixels, all those
pixels are again reassigned to the next nearest cluster. New cluster means
are calculated for each band as the average of raster pixel values in that
band for all pixels present in that cluster.
<p>
In the 2nd pass, pixels are then again reassigned to clusters based on new
cluster means. The cluster means are then again recalculated.  This
process is repeated until the correspondence between iterations reaches a
user-specified level, or till the maximum number of iterations specified is
over, whichever comes first.

<h2>EXAMPLE</h2>

Preparing the statistics for unsupervised classification of
a LANDSAT subscene in North Carolina:

<div class="code"><pre>
## Prepare imagery for classification
# Skip this step if your rasters already have band references defined
# Define band references for all LANDSAT bands in mapset PERMANENT
g.mapset mapset=PERMANENT
r.support map=lsat7_2002_10 bandref=TM7_1
r.support map=lsat7_2002_20 bandref=TM7_2
r.support map=lsat7_2002_30 bandref=TM7_3
r.support map=lsat7_2002_40 bandref=TM7_4
r.support map=lsat7_2002_50 bandref=TM7_5
r.support map=lsat7_2002_61 bandref=TM7_61
r.support map=lsat7_2002_62 bandref=TM7_62
r.support map=lsat7_2002_70 bandref=TM7_7
r.support map=lsat7_2002_80 bandref=TM7_8
g.mapset mapset=user1  # replace user1 with your mapset name

## Real work starts here
# Set computational region to match the scene
g.region raster=lsat7_2002_10 -p

# store VIZ, NIR, MIR into group/subgroup (leaving out TIR)
i.group group=lsat7_2002 subgroup=res_30m \
  input=lsat7_2002_10,lsat7_2002_20,lsat7_2002_30,lsat7_2002_40,lsat7_2002_50,lsat7_2002_70

# generate signature file and report
i.cluster group=lsat7_2002 subgroup=res_30m \
  signaturefile=cluster_lsat2002 \
  classes=10 reportfile=rep_clust_lsat2002.txt
</pre></div>

To complete the unsupervised classification, <em>i.maxlik</em> is subsequently used.
See example in its manual page.

<h2>SEE ALSO</h2>

<ul>
<li> <a href="https://grasswiki.osgeo.org/wiki/Image_classification">Image classification</a> wiki page</li>
<li> Historical reference also the GRASS GIS 4 
     <a href="https://grass.osgeo.org/gdp/imagery/grass4_image_processing.pdf">Image Processing manual</a> (PDF)</li>
<li> <a href="https://en.wikipedia.org/wiki/K-means_clustering">Wikipedia article on <i>k</i>-means clustering</a>
     (note that <em>i.cluster</em> uses a modification of the <i>k</i>-means clustering algorithm)</li>
</ul>

<p>
<em>
<a href="r.support.html">r.support</a>,
<a href="g.gui.iclass.html">g.gui.iclass</a>,
<a href="i.group.html">i.group</a>,
<a href="i.gensig.html">i.gensig</a>,
<a href="i.maxlik.html">i.maxlik</a>,
<a href="i.segment.html">i.segment</a>,
<a href="i.smap.html">i.smap</a>,
<a href="r.kappa.html">r.kappa</a>
</em>

<h2>AUTHORS</h2>

Michael Shapiro,
U.S. Army Construction Engineering Research Laboratory
<br>
Tao Wen, 
University of Illinois at Urbana-Champaign, Illinois
<br>
Band reference support: Maris Nartiss,
University of Latvia

<!--
<p>
<i>Last changed: $Date$</i>
-->
